Lecture 7: Webscraping: (2) Client-side and APIs

External software

Today I’ll be using JSONView, a browser extension that renders JSON output nicely in Chrome and Firefox. (Not needed, but recommended.)

R packages

• New: jsonlite, listviewer
• Already used: tidyverse, lubridate, hrbrthemes

Install these new packages now:

## Not run. (Run this manually yourself if you haven't installed these packages yet.)
install.packages(c("jsonlite", "listviewer"))

We might as well load the tidyverse now, since we’ll be using that a fair bit anyway. I’ll also set my preferred ggplot2 theme for the rest of this document.

library(tidyverse)
theme_set(hrbrthemes::theme_ipsum())

Student presentation: APIs

If you’re new to APIs or reading this after the fact, then I recommend this excellent resource from Zapier: An Introduction to APIs. It’s short, but you don’t need to work through the whole thing to get the gist.

The summary version is that an API is really just a collection of rules and methods that allow different software applications to interact and share information. This includes not just websites and browsers, but also software packages like the R libraries we’ve been using.¹

A bit more about API endpoints

A key point in all of this is that, in the case of web APIs, we can access information directly from the API database if we can specify the correct URL(s). These URLs are known as an API endpoints.

API endpoints are in many ways similar to the normal website URLs that we’re all used to visiting. For starters, you can navigate to them in your web browser. However, whereas normal websites display information in rich HTML content — pictures, cat videos, nice formatting, etc. — an API endpoint is much less visually appealing. Navigate your browser to an API endpoint and you’ll just see a load of seemingly unformatted text. In truth, what you’re really seeing is (probably) either JSON (JavaScript Object Notation) or XML (Extensible Markup Language).

You don’t need to worry too much about the syntax of JSON and XML. The important thing is that the object in your browser — that load of seemingly unformatted text — is actually very precisely structured and formatted. Moreover, it contains valuable information that we can easily read into R (or Python, Julia, etc.) We just need to know the right API endpoint for the data that we want.

Let’s practice doing this through a few example applications. I’ll start with the simplest case (no API key required, explicit API endpoint) and then work through some more complicated examples.

Locating the hidden API endpoint

Fortunately, there’s a better way: Access the full database of rankings through the API. First we have to find the endpoint, though. Start by inspecting the page like we practised last lecture. (Ctr+Shift+I in Chrome. Ctrl+Shift+Q in Firefox.) This time, however, rather than mousing over individual objects on the page, head to the Network tab at the top of the inspect element panel. Then click on XHR.⁵

Refresh the page (Ctrl+R). You should see something like the below, which captures all traffic coming to and from the page. Our task now is to scroll these different links and see which one contains the information that we’re after. In this case, that’s the rugby rankings, but we could also look for other information on the page like upcoming matches.

The item that I’ve highlighted brings up a URL called https://cmsapi.pulselive.com/rugby/rankings/mru?language=en&client=pulse.

Hmmm… “API” you say? “Rankings” you say? Sounds promising.

Let’s click on this item and then open up the Preview tab.

Again, this looks good. We can see what looks the first row of the rankings table (“New Zealand”, etc.) To make sure, go back to the Headers tab, grab that https://cmsapi.pulselive.com/rugby/rankings/mru?language=en&client=pulse, and paste it into our browser. Note that I’m using the JSONView browser plugin for nicely rendered JSON output, so don’t be alarmed if your screen looks different to mine.

Boom. We’ve located our API endpoint. Let’s pull the data into R.

Pulling the data into R

There are several packages for reading web-based (and web API) data into R. The httr package that comes bundled with the tidyverse is a good example, while the curl package is another (very powerful) option. However, for the below I’m just going to use the jsonlite package’s fromJSON() function, which is perfect for reading in JSON objects like our API endpoint.

endpoint <- "https://cmsapi.pulselive.com/rugby/rankings/mru?language=en&client=pulse"
rugby <- fromJSON(endpoint)
str(rugby)

## List of 3
##  $ label    : chr "Mens Rugby Union"
##  $ entries  :'data.frame':   105 obs. of  6 variables:
##   ..$ team       :'data.frame':  105 obs. of  5 variables:
##   .. ..$ id          : int [1:105] 37 36 33 34 39 38 35 46 42 40 ...
##   .. ..$ altId       : logi [1:105] NA NA NA NA NA NA ...
##   .. ..$ name        : chr [1:105] "New Zealand" "Ireland" "Wales" "England" ...
##   .. ..$ abbreviation: chr [1:105] "NZL" "IRE" "WAL" "ENG" ...
##   .. ..$ annotations : logi [1:105] NA NA NA NA NA NA ...
##   ..$ matches    : int [1:105] 209 182 196 189 200 217 177 111 187 182 ...
##   ..$ pts        : num [1:105] 92.5 91.2 87.2 86.2 84.6 ...
##   ..$ pos        : int [1:105] 1 2 3 4 5 6 7 8 9 10 ...
##   ..$ previousPts: num [1:105] 92.5 91.2 87.2 86.2 84.6 ...
##   ..$ previousPos: int [1:105] 1 2 3 4 5 6 7 8 9 10 ...
##  $ effective:List of 3
##   ..$ millis   : num 1.55e+12
##   ..$ gmtOffset: num 0
##   ..$ label    : chr "2019-01-07"

So we have a nested list, where what looks to be the main element of interest, $entries, is itself a list.⁶ Nested lists are the law of the land when it comes to JSON data. Don’t worry too much about this now, but R ideally suited to handling this type of nested information. We’ll see more examples later in the course when we start working with spatial data (e.g. geoJSON) and you’ll even find that the nested structure can prove very powerful once you start doing more advanced programming and analysis in R.

Okay, let’s extract the $entries element and have a look at its structure. We could use the str() base function, but for complicated list elements the interactive widget provided by listviewer::jsonedit() is hard to beat. For completeness, I’ll then also preview the $entries$team sub-element.

# str(rugby$entries) ## Base option
listviewer::jsonedit(rugby, mode = "view")

head(rugby$entries$team)

##   id altId         name abbreviation annotations
## 1 37    NA  New Zealand          NZL          NA
## 2 36    NA      Ireland          IRE          NA
## 3 33    NA        Wales          WAL          NA
## 4 34    NA      England          ENG          NA
## 5 39    NA South Africa          RSA          NA
## 6 38    NA    Australia          AUS          NA

It looks like like we can just bind the $entires$team data frame directly to the other elements of the parent $team “data frame” (actually: “list”). Let’s do that and then clean things up a bit. I’m going to call the resulting data frame rankings.

library(janitor)

rankings <-
  bind_cols(
    rugby$entries$team,
    rugby$entries %>% select(matches:previousPos)
  ) %>%
  clean_names() %>%
  select(-c(id, alt_id, annotations)) %>% ## These columns aren't adding much of interest
  select(pos, pts, everything()) %>% ## Reorder remaining columns
  as_tibble() ## "Enhanced" tidyverse version of a data frame
rankings

## # A tibble: 105 x 7
##      pos   pts name         abbreviation matches previous_pts previous_pos
##    <int> <dbl> <chr>        <chr>          <int>        <dbl>        <int>
##  1     1  92.5 New Zealand  NZL              209         92.5            1
##  2     2  91.2 Ireland      IRE              182         91.2            2
##  3     3  87.2 Wales        WAL              196         87.2            3
##  4     4  86.2 England      ENG              189         86.2            4
##  5     5  84.6 South Africa RSA              200         84.6            5
##  6     6  82.4 Australia    AUS              217         82.4            6
##  7     7  81.8 Scotland     SCO              177         81.8            7
##  8     8  77.9 Fiji         FJI              111         77.9            8
##  9     9  77.3 France       FRA              187         77.3            9
## 10    10  77.0 Argentina    ARG              182         77.0           10
## # … with 95 more rows

BONUS: Get and plot the rankings history

The above looks great, except for the fact that its just a single snapshot of the most recent rankings. We are probably more interested in looking back at changes in the ratings over time. For example, back to an era when South Africa wasn’t so kak.

How do we do this? Well, in the spirit of art-vs-science, let’s open up the Inspect window of the rankings page again and start exploring. What happens if we click on the calendar element, say, change the month to “April”?

This looks promising! Essentially, the same API endpoint that we saw previously, but now appended with a date, https://cmsapi.pulselive.com/rugby/rankings/mru?date=2018-05-01&client=pulse. If you were to continue along in this manner – clicking on the website calendar and looking for XHR traffic – you would soon realise that these date suffixes follow a predictable pattern: They are spaced out a week apart and always fall on a Monday. In other words, the World Rugby updates its rankings table weekly and publishes the results on Mondays.

We now have enough information to write a function that will loop over a set of dates and pull data from the relevant API endpoint. NB: I know we haven’t gotten to the programming section of the course, so don’t worry about the specifics of the next few code chunks. I’ll try to comment my code quite explicitly, but I mostly want you to focus on the big picture.

To start, we need a vector of valid dates to loop over. I’m going to use various functions from the lubridate package to help with this. Note that I’m only to extract a few data points — one observation a year for the last decade or so — since I just want to demonstrate the principle. No need to hammer the host server. (More on that below.)

library(lubridate)

## 
## Attaching package: 'lubridate'

## The following object is masked from 'package:base':
## 
##     date

## We'll look at rankings around Jan 1st each year. I'll use 2004 as an
## arbitrary start year and then proceed until the present year.
start_date <- ymd("2004-01-01")
end_date <- floor_date(today(), unit="years")
dates <- seq(start_date, end_date, by="years")
## Get the nearest Monday to Jan 1st to coincide with rankings release dates.
dates <- floor_date(dates, "week", week_start = getOption("lubridate.week.start", 1))
dates

##  [1] "2003-12-29" "2004-12-27" "2005-12-26" "2007-01-01" "2007-12-31"
##  [6] "2008-12-29" "2009-12-28" "2010-12-27" "2011-12-26" "2012-12-31"
## [11] "2013-12-30" "2014-12-29" "2015-12-28" "2016-12-26" "2018-01-01"
## [16] "2018-12-31"

Next, I’ll write out a function that I’ll call rugby_scrape. This function will take a single argument; namely a date that it will use to construct a new API endpoint during each iteration. Beyond that, it will do pretty much exactly the same things that we did in our previous, manual data scrape. The only other difference is that it will wait three seconds after running (i.e. Sys.sleep(3)). I’m adding this final line to avoid hammering the server with instantaneous requests when we put everything into a loop.

## First remove our existing variables. This is not really necessary, since R is smart enough
## to distinguish named objects in functions from named objects in our global environment.
## But I want to emphasise the we're creating new data here and avoid any confusion.
rm(rugby, rankings, endpoint)

## Now, create the function. I'll call it "rugby_scrape".
rugby_scrape <- 
  function(x) {
    endpoint <- paste0("https://cmsapi.pulselive.com/rugby/rankings/mru?date=", x, "&client=pulse")
    rugby <- fromJSON(endpoint)
    rankings <-
      bind_cols(
        rugby$entries$team,
        rugby$entries %>% select(matches:previousPos)
        ) %>%
      clean_names() %>%
      mutate(date = x) %>% ## New column to keep track of the date 
      select(-c(id, alt_id, annotations)) %>% ## These columns aren't adding much of interest
      select(date, pos, pts, everything()) %>% ## Reorder remaining columns
      as_tibble() ## "Enhanced" tidyverse version of a data frame
    Sys.sleep(3) ## Be nice!
    return(rankings)
  }

Finally, we can now iterate (i.e. loop) over our dates vector, by plugging the values sequentially into our rugby_scrape function. There are a variety of ways to iterate in R, but I’m going to use an lapply() call below.⁷ We’ll then bind everything into a single data frame using dplyr::bind_rows() and name the resulting object rankings_history.

rankings_history <-
  lapply(dates, rugby_scrape) %>% ## Run the iteration
  bind_rows() ## Bind the resulting list of data frames into a single data frame
rankings_history

## # A tibble: 1,569 x 8
##    date         pos   pts name  abbreviation matches previous_pts
##    <date>     <int> <dbl> <chr> <chr>          <int>        <dbl>
##  1 2003-12-29     1  94.0 Engl… ENG               17         92.1
##  2 2003-12-29     2  90.1 New … NZL               17         88.2
##  3 2003-12-29     3  86.6 Aust… AUS               17         88.4
##  4 2003-12-29     4  82.7 Fran… FRA               17         84.7
##  5 2003-12-29     5  81.2 Sout… RSA               15         81.2
##  6 2003-12-29     6  80.5 Irel… IRE               15         80.5
##  7 2003-12-29     7  78.0 Arge… ARG               14         78.0
##  8 2003-12-29     8  76.9 Wales WAL               15         76.9
##  9 2003-12-29     9  76.4 Scot… SCO               15         76.4
## 10 2003-12-29    10  73.5 Samoa SAM               14         73.5
## # … with 1,559 more rows, and 1 more variable: previous_pos <int>

Let’s review what we just did:

• We created a vector of dates — creatively called dates — with observations evenly spaced (about) a year apart, falling on the Monday closest to Jan 1st for that year.
• We then iterated (i.e. looped) over these dates using a function, rugby_scrape, which downloaded and cleaned data from the relevant API endpoint.
• At the end of each iteration, we told R to wait a few seconds before executing the next step. The reason is that R can execute these steps much, much quicker than we could ever type them manually. It probably doesn’t matter for this example, but you can easily “overwhelm” a host server by hammering it with a loop of automated requests. (Or, just as likely: They have safeguards against this type of behaviour and will start denying your requests as a suspected malicious attack.) The “be nice” motto is important to remember when scraping API data.
• Note that each run of our iteration will have produced a separate data frame, which lapply() by default appends into a list. We used dplyr::bind_rows() to bid these separate data frames into a single data frame.

Okay! Let’s plot the data and highlight a select few countries in the process.

teams <- c("NZL", "RSA", "ENG", "JPN")
team_cols <- c("NZL"="black", "RSA"="#4DAF4A", "ENG"="#377EB8", "JPN" = "red")

rankings_history %>%
  ggplot(aes(x=date, y=pts, group=abbreviation)) +
  geom_line(col = "grey") + 
  geom_line(
    data = rankings_history %>% filter(abbreviation %in% teams), 
    aes(col=fct_reorder2(abbreviation, date, pts)),
    lwd = 1
    ) +
  scale_color_manual(values = team_cols) +
  labs(
    x = "Date", y = "Points", 
    title = "International rugby rankings", caption = "Source: World Rugby"
    ) +
  hrbrthemes::theme_ipsum() +
  theme(legend.title = element_blank())